---
title: 세션
description: Persist multi-turn conversation history so agents can resume context across runs.
---

import { Code } from '@astrojs/starlight/components';
import sessionsQuickstart from '../../../../../../examples/docs/sessions/basicSession.ts?raw';
import manageHistory from '../../../../../../examples/docs/sessions/manageHistory.ts?raw';
import customSession from '../../../../../../examples/docs/sessions/customSession.ts?raw';
import sessionInputCallback from '../../../../../../examples/docs/sessions/sessionInputCallback.ts?raw';

Sessions는 Agents SDK에 **영구 메모리 계층**을 제공합니다. `Session` 인터페이스를 구현한 아무 객체나 `Runner.run`에 전달하면, 나머지는 SDK가 처리합니다. 세션이 있으면 러너는 자동으로 다음을 수행합니다.

1. 이전에 저장된 대화 항목을 가져와 다음 턴 앞에 붙입니다.
2. 각 실행이 완료된 후 새로운 사용자 입력과 assistant 출력을 지속 저장합니다.
3. 새 사용자 텍스트로 러너를 호출하든 인터럽션(중단 처리)된 `RunState`에서 재개하든, 향후 턴을 위해 세션을 사용 가능 상태로 유지합니다.

이를 통해 수동으로 `toInputList()`를 호출하거나 턴 간 히스토리를 이어 붙일 필요가 없습니다. TypeScript SDK에는 두 가지 구현이 포함되어 있습니다: Conversations API용 `OpenAIConversationsSession`과 로컬 개발을 위한 `MemorySession`. 둘 다 `Session` 인터페이스를 공유하므로, 자체 스토리지 백엔드를 쉽게 연결할 수 있습니다. Conversations API를 넘어서는 영감이 필요하다면 `examples/memory/` 아래의 샘플 세션 백엔드(Prisma, 파일 기반 등)를 살펴보세요.

> 팁: 이 페이지의 `OpenAIConversationsSession` 예제를 실행하려면 `OPENAI_API_KEY` 환경 변수를 설정하세요(또는 세션 생성 시 `apiKey`를 제공). 그러면 SDK가 Conversations API를 호출할 수 있습니다.

---

## 빠른 시작

`OpenAIConversationsSession`을 사용해 [Conversations API](https://platform.openai.com/docs/api-reference/conversations)와 메모리를 동기화하거나, 다른 어떤 `Session` 구현으로 교체하세요.

<Code
  lang="typescript"
  code={sessionsQuickstart}
  title="Conversations API를 세션 메모리로 사용"
/>

동일한 세션 인스턴스를 재사용하면 에이전트가 매 턴 전에 전체 대화 히스토리를 받으며 새로운 항목도 자동으로 지속 저장됩니다. 다른 `Session` 구현으로 전환하더라도 코드 변경은 필요 없습니다.

---

## 러너의 세션 사용 방식

- **각 실행 전** 세션 히스토리를 가져와 새 턴의 입력과 병합하고, 결합된 리스트를 에이전트에 전달합니다.
- **스트리밍이 아닌 실행 후** 한 번의 `session.addItems()` 호출로 최신 턴의 원본 사용자 입력과 모델 출력을 모두 저장합니다.
- **스트리밍 실행의 경우** 사용자 입력을 먼저 기록하고, 턴이 완료되면 스트리밍된 출력을 추가로 기록합니다.
- **`RunResult.state`에서 재개할 때**(승인 또는 기타 인터럽션) 동일한 `session`을 계속 전달하세요. 재개된 턴은 입력을 다시 준비하지 않고 메모리에 추가됩니다.

---

## 히스토리 검사 및 편집

세션은 간단한 CRUD 도우미를 제공하므로 "실행 취소", "채팅 지우기" 또는 감사 기능을 구축할 수 있습니다.

<Code lang="typescript" code={manageHistory} title="저장된 항목 읽기 및 편집" />

`session.getItems()`는 저장된 `AgentInputItem[]`을 반환합니다. `popItem()`을 호출해 마지막 항목을 제거하세요—에이전트를 다시 실행하기 전에 사용자가 수정할 때 유용합니다.

---

## 사용자 스토리지 사용

`Session` 인터페이스를 구현하여 Redis, DynamoDB, SQLite 또는 다른 데이터스토어로 메모리를 지원하세요. 필요한 것은 비동기 메서드 다섯 개뿐입니다.

<Code
  lang="typescript"
  code={customSession}
  title="사용자 정의 인메모리 세션 구현"
/>

커스텀 세션을 사용하면 보존 정책을 강제하고, 암호화를 추가하거나, 지속 저장 전에 각 대화 턴에 메타데이터를 첨부할 수 있습니다.

---

## 히스토리와 신규 항목 병합 제어

실행 입력으로 `AgentInputItem` 배열을 전달할 때, 저장된 히스토리와 결정적으로 병합하려면 `sessionInputCallback`을 제공하세요. 러너는 기존 히스토리를 로드하고, **모델 호출 전에** 콜백을 호출한 뒤, 반환된 배열을 해당 턴의 완전한 입력으로 모델에 전달합니다. 이 훅은 오래된 항목을 잘라내거나, 도구 결과의 중복을 제거하거나, 모델이 보길 원하는 컨텍스트만 강조하는 데 적합합니다.

<Code
  lang="typescript"
  code={sessionInputCallback}
  title="sessionInputCallback으로 히스토리 절단"
/>

문자열 입력의 경우 러너가 히스토리를 자동 병합하므로 콜백은 선택 사항입니다.

---

## 승인 및 재개 가능한 실행 처리

휴먼인더루프 (HITL) 플로우는 종종 승인을 기다리기 위해 실행을 일시 중지합니다:

```typescript
const result = await runner.run(agent, 'Search the itinerary', {
  session,
  stream: true,
});

if (result.requiresApproval) {
  // ... collect user feedback, then resume the agent in a later turn
  const continuation = await runner.run(agent, result.state, { session });
  console.log(continuation.finalOutput);
}
```

이전 `RunState`에서 재개할 때, 단일 대화 히스토리를 보존하기 위해 새 턴이 동일한 메모리 레코드에 추가됩니다. 휴먼인더루프 (HITL) 플로우는 완전히 호환되며—승인 체크포인트는 계속 `RunState`를 통해 왕복되고, 세션은 전체 대화 기록을 유지합니다.
